home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_libdockapp.idb / usr / freeware / include / dockapp.h.z / dockapp.h
C/C++ Source or Header  |  2002-04-08  |  7KB  |  242 lines
  1. /*
  2.  * Copyright (c) 1999 Alfredo K. Kojima
  3.  *
  4.  * Permission is hereby granted, free of charge, to any person obtaining a copy
  5.  * of this software and associated documentation files (the "Software"), to deal
  6.  * in the Software without restriction, including without limitation the rights
  7.  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  8.  * copies of the Software, and to permit persons to whom the Software is
  9.  * furnished to do so, subject to the following conditions:
  10.  *
  11.  * The above copyright notice and this permission notice shall be included in
  12.  * all copies or substantial portions of the Software.
  13.  *
  14.  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15.  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16.  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  17.  * AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  18.  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  19.  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  20.  * 
  21.  * $Id: dockapp.h,v 1.13 2000/02/18 12:31:22 daeron Exp $
  22.  */
  23.  
  24. #ifndef _DOCKAPP_H_
  25. #define _DOCKAPP_H_
  26.  
  27. /*
  28.  * This is a simple (trivial) library for writing Window Maker dock
  29.  * applications, or dockapps (those that only show up in the dock), easily.
  30.  *
  31.  * It is very limited and can be only used for dockapps that open a single
  32.  * appicon for process in only ibe single display, but this seems to be
  33.  * enough for most, if not all, dockapps.
  34.  */
  35.  
  36. #include <X11/Xlib.h>
  37. #include <X11/xpm.h>
  38. #include <stdlib.h>
  39. #include <stdio.h>
  40.  
  41.  
  42.  
  43. /*
  44.  * the callbacks for events related to the dockapp window your program wants
  45.  * to handle
  46.  */
  47. typedef struct {
  48.     /* the dockapp window was destroyed */
  49.     void (*destroy)(void);
  50.     /* button pressed */
  51.     void (*buttonPress)(int button, int state, int x, int y);
  52.     /* button released */
  53.     void (*buttonRelease)(int button, int state, int x, int y);
  54.     /* pointer motion */
  55.     void (*motion)(int x, int y);
  56.     /* pointer entered dockapp window */
  57.     void (*enter)(void);
  58.     /* pointer left dockapp window */
  59.     void (*leave)(void);
  60.     /* timer expired */
  61.     void (*timeout)(void);
  62. } DACallbacks;
  63.  
  64.  
  65. typedef struct {
  66.     char    *shortForm;    /* short form for option, like -w    */
  67.     char    *longForm;    /* long form for option, like --withdrawn */
  68.     char    *description;    /* description for the option        */
  69.     
  70.     short    type;        /* type of argument            */
  71.     Bool    used;        /* if the argument was passed on the cmd-line */
  72.     
  73.     /* the following are only set if the "used" field is True        */
  74.     union {
  75.     void    *ptr;        /* a ptr for the value that was passed    */
  76.     int    *integer;    /* on the command line            */
  77.     char    **string;
  78.     } value;
  79. } DAProgramOption;
  80.  
  81. typedef struct {
  82.     int        x, y;
  83.     int        width, height;
  84. } DARect;
  85.  
  86. typedef void DARectCallback(int x, int y, DARect rect, void *data);
  87.  
  88. typedef struct {
  89.     DARect        rect;
  90.     DARectCallback    *action;
  91. } DAActionRect;
  92.  
  93.  
  94. /* option argument types */
  95. enum {
  96.     DONone,            /* simple on/off flag            */
  97.     DOInteger,            /* an integer number            */
  98.     DOString,            /* a string                */
  99.     DONatural            /* positive integer number        */
  100. };
  101.  
  102.  
  103. extern Display    *DADisplay;
  104. extern Window    DAWindow;
  105. extern int    DADepth;
  106. extern Visual    *DAVisual;
  107. extern GC    DAGC;
  108. extern DARect    DANoRect;
  109.  
  110.  
  111. /*
  112.  * DAParseArguments-
  113.  *    Command line arguments parser. The program is exited if there are
  114.  * syntax errors.
  115.  *
  116.  * -h, --help and --version are automatically handled (causing the program
  117.  * to exit)
  118.  * -w is handled automatically as well and causes the dockapp to be run
  119.  * in windowed mode.
  120.  */
  121. void DAParseArguments(int argc, char **argv, DAProgramOption *options,
  122.     int count, char *programDescription, char *versionDescription);
  123.  
  124. /*
  125.  * DAInitialize-
  126.  *    Initialize the dockapp, open a connection to the X Server,
  127.  * create the needed windows and set them up to become an appicon  window.
  128.  * It will automatically detect if Window Maker is present and use
  129.  * an appropriate window form.
  130.  *
  131.  * You must call this always before calling anything else (except for
  132.  * DAParseArguments())
  133.  *
  134.  * Arguments:
  135.  *    display        - the name of the display to connect to.
  136.  *            Use "" to use the default value.
  137.  *    name        - the name of your dockapp, used as the instance name
  138.  *            for the WM_CLASS hint. Like wmyaclock.
  139.  *            The ClassName is set to "DockApp" on default.
  140.  *    width, height    - the size of the dockapp window. 48x48 is the
  141.  *            preferred size.
  142.  *    argc, argc    - the program arguments. argv[0] will be used
  143.  *            as the instance name for the WM_CLASS hint.
  144.  */
  145. void DAInitialize(char *display, char *name, unsigned width, unsigned height,
  146.     int argc, char **argv);
  147.  
  148. /*
  149.  * DASetShapeWithOffset-
  150.  *    Sets the shape mask of the dockapp to the specified one. This is
  151.  * optional. If you pass None as shapeMask, the dockapp will become
  152.  * non-shaped.
  153.  *
  154.  * This is only needed if you want the dockapp to be shaped.
  155.  */
  156. #define DASetShape(shapeMask)    (DASetShapeWithOffset((shapeMask), 0, 0))
  157. void DASetShapeWithOffset(Pixmap shapeMask, int x_ofs, int y_ofs);
  158.  
  159. /*
  160.  * DASetPixmap-
  161.  *    Sets the image pixmap for the dockapp. Once you set the image with it,
  162.  * you don't need to handle expose events.
  163.  */
  164. void DASetPixmap(Pixmap pixmap);
  165.  
  166. /*
  167.  * DAMakePixmap-
  168.  *    Creates a pixmap suitable for use with DASetPixmap()
  169.  */
  170. Pixmap DAMakePixmap(void);
  171.  
  172. /*
  173.  * DAMakePixmapFromData-
  174.  *    Creates a pixmap and mask from XPM data
  175.  */
  176. Bool DAMakePixmapFromData(char **data, Pixmap *pixmap, Pixmap *mask,
  177.     unsigned *width, unsigned *height);
  178.  
  179. /*
  180.  * DAGetColor-
  181.  *    Returns a color.
  182.  */
  183. unsigned long DAGetColor(char *colorName);
  184.  
  185. /*
  186.  * DAShow-
  187.  *    Opens the dockapp.
  188.  *
  189.  * Always call this function or the dockapp won't show up.
  190.  */
  191. void DAShow(void);
  192.  
  193. /*
  194.  * DASetCallbacks-
  195.  *    Register a set of callbacks for events like mouse clicks.
  196.  *
  197.  * Only needed if you want to receive some event.
  198.  */
  199. void DASetCallbacks(DACallbacks *callbacks);
  200.  
  201. /*
  202.  * DASetTimeout-
  203.  *    Sets a timeout for the DAEventLoop(). The timeout callback
  204.  * will be called whenever the app doesn't get any events from the
  205.  * X server in the specified time.
  206.  */
  207. void DASetTimeout(int miliseconds);
  208.  
  209. /*
  210.  * DANextEventOrTimeout-
  211.  *    Waits until a event is received or the timeout limit has
  212.  * expired. Returns True if an event was received.
  213.  */
  214. Bool DANextEventOrTimeout(XEvent *event, unsigned long miliseconds);
  215.  
  216. /*
  217.  * DAProcessEvent-
  218.  *    Processes an event. Returns True if the event was handled and
  219.  * False otherwise.
  220.  *
  221.  * Must be called from your event loop, unless you use DAEventLoop()
  222.  */
  223. Bool DAProcessEvent(XEvent *event);
  224.  
  225. /*
  226.  * DAEventLoop-
  227.  *    Enters an event loop where events are processed until the dockapp
  228.  * is closed. This function never returns.
  229.  */
  230. void DAEventLoop(void);
  231.  
  232. /*
  233.  * DAProcessActionRects-
  234.  *     Processes the current coordinates for the functions in the array of
  235.  * action rectangles, converting coordinates to relative coordinates in
  236.  * the rectangles. The last item must be NULL.
  237.  */
  238. void DAProcessActionRects(int x, int y, DAActionRect *actionrects,
  239.     int count, void *data);
  240.  
  241. #endif
  242.